Graphics Plus/Graphics Plus.iso/general/viewers/polyview/plyvw102.lha/PolyView1.02/polyview.2

Text File | 1991-07-02 | 19KB | 685 lines

Command References    2.1




August 1990







2.1    NCSA PolyView





Chapter 2    Command References



Chapter Overview
Command Line Parameters
Usage
Data Parameters
HDF File
Group Parameter
PX, PY, PZ Parameters
Connect Parameter
Scalar Parameter
Raw Palette File
ris8out File
Fly File
Control Parameters
From
Axes
Box
Constant
Labels
Lines
Points
Polygons
At Point
View Menu
Projection Submenu
Draw Submenu
Shade Submenu
Palette Submenu
Overlay Submenu
Animate Submenu
Fly Option
Pop Option
Redraw Option
Reset Option
WriteHDF Option
Confirm Submenu


Chapter Overview

This chapter describes the batch and interactive command options
available for PolyView. Command line data and control
parameters are presented, as well as pop-up menu and keyboard
options.


Command Line Parameters

This section describes the command line parameters available to
you when starting up PolyView. Command line parameters are
options provided to the program, typically prefixed by a hyphen and
followed by other information, when the command is executed.

For example, in the following entry:

polyview -hdf demo.hdf -scalar random -fly demo.fly

the strings -hdf, -scalar, and -fly are the parameters that
control the execution of the program.

This section begins by providing a list of all the parameters
available to the user, then provides more detail about each of them,
drawing a distinction between data and control parameters .


Usage

Typing polyview without any arguments lists the legal
parameters available to the user, as shown below.

usage:    polyview
    -hdf <string>
    [-palette <string>]
    [-ris8out <string>]
    [-group <string>]
    [-fly <string>]
    [-px <string>]
    [-py <string>]
    [-pz <string>]
    [-connect <string>]
    [-scalar <string>]
    [-from <float> <float> <float>]
    [-axes]
    [-box]
    [-constant]
    [-labels]
    [-points]
    [-lines]
    [-polygons]
    [-at_point]


The -hdf parameter is the only mandatory option. All other data
and control parameters are optional and have reasonable defaults.
Optional parameters are surrounded by square brackets.

Parameters may be specified in any reasonable order, as long as
you provide the proper arguments. In the usage listing above, each
argument-type name is surrounded by angle brackets.


Data Parameters

This section describes the command line parameters that
determine which files, vgroups, and vdatas are used as sources of
data for the PolyView session.

HDF File
-hdf filename
The -hdf parameter specifies the name of the file that is to be used
for input to the program. The filename may be the name of any
HDF Vset format file.

NOTE:  This parameter is mandatory. If it is not present,
PolyView refuses to run.


Group Parameter
-group groupname
The -group parameter specifies the groupname of the vgroup(s)
which contain the data you want to view. PolyView scans the
vgroup(s) matching the groupname for vdatas which you specified
using other data command parameters.

The groupname may contain an asterisk as a wildcard character,
but only at the end of the string. The program reads all vgroups
with names that match the groupname  into memory.

The data in each vgroup is assumed to form one frame in an
animation sequence. If PolyView reads in more than one frame,
then it can animate the set of frames when you use the Animation
submenu.

With a set of animation frames, you might want to specify group
names using a wildcard character in the group name parameter at
startup. For example, if the groups are named group01, group02,
and group03 a good group name might be group*.

Each vgroup describes one frame of the animation sequence. Any
data missing from a given group (such as vertex or connectivity
data) is obtained from the last vgroup that it was present in. This
system avoids requiring redundant information.

For example, consider a finite element simulation with constant
structural data (vertices and connectivity), but with varying
scalar data (compression, temperature, voltage, etc.). All groups
would contain their own unique scalar datasets, but only one of
them would need to contain a copy of the structural data since it is
the same for all frames.

Default:  The groupname defaults to "*", which tells PolyView to
load all of the vgroups in the file.


PX,  PY,  PZ Parameters
-px pxname
-py pyname
-pz pzname

The -px, -py, and -pz parameters specify the names of the x, y,
and z coordinate datasets. If datasets do not exit, default float
datasets indicate x, y, and z coordinates of image vertices.

Default:  The pxname, pyname, and pzname default to px, py, and
pz, respectively.


Connect Parameter
-connect connectname
The -connect parameter specifies the connectname of the
connectivity dataset.

The integer dataset connect specifies connectivity of vertices.
Three- and four-vertex polygons are supported as dataset types. A
connect dataset named plist3 is always assumed to be composed
of groups of three vertex ids each. All other datasets are assumed to
be composed of groups of four vertex ids each. If PolyView doesn't
find any connectivity information, it displays the data as a field of
points.

Default:  The connectname defaults to plist4.


Defining Polygons
Connectivity information defines polygons. Each polygon is
described by the vertex ids of the vertices that comprise it. The
vertex ids index into the px, py, and pz datasets to specify the vertex
coordinates. The ids are numbered from 1 to n, where n is the
number of vertices in this group.


Mixing Polygons
To mix three- and four-vertex polygons in the same dataset, use a
four-vertex dataset (i.e., one named something other than
plist3). In such a scheme, four-vertex polygons are represented
as usual. Three-vertex polygons are composed of the three vertex-
ids and a "0" for the last vertex id. The zero indicates a "null" or
non-existant vertex.

As an example, consider a square and a triangle (Figure 2.1). The
square is composed of four vertices and the triangle of three. The
entry in the connect dataset for the square contains all four vertex
ids. The entry for the triangle only connects three, followed by a
zero.

Figure 2.1    Three- and Four-
Vertex Polygons



NOTE:   Vertices are numbered starting with 1 (the FORTRAN
convention, rather than C's 0).


Scalar Parameter
-scalar scalarname
The -scalar parameter specifies the scalarname of the scalar
value vdata.

The scalarname vdata is a float vdata whose values are mapped to
the colors used to draw lines and polygons. If the vdata is not
found, the foreground color (white) is used for all drawing.

Default:  The scalarname defaults to scalar.


Raw Palette File
-palette filename
The -palette parameter specifies the filename of a raw palette
file. PolyView reloads the palette into the program at startup; it can
reload a palette at any time when you choose the from file option
from the palette submenu.

If you choose the from file menu option without having specified a
palette filename on the command line, PolyView  prints the
following warning message:

    Please specify palette file on command line using
the '-palette' switch for this option.


A raw palette file defines a palette of 256 colors in terms of their
red, green, and blue components. The color component values are
expected to be written in binary format using the C fwrite()
function or equivalent Fortran command.

Component values are based on the red, green, and blue
representation of color, the RGB color model. The values consist of,
in order, 256 bytes of red, 256 bytes of green, and 256 bytes of blue.
The 256 color palette entries are calculated by combining the nth
element (red), the (n+256)th element (green), and the (n+512)th
element (blue) to create the nth RGB component.

PolyView rereads the raw palette every time you choose the from
file option from the palette menu, located in the Palette window.

The programs uses the 0th color palette entry for the background
color and the 255th entry for the foreground color (used for
overlays).

All palettes should have colors 0 and 255 mapping to the
background and foreground colors (black and white),
respectively. The other colors are free to change as necessary.

Default:  No default exists.


ris8out File
-ris8out filename
The -ris8out parameter specifies the filename to which PolyView
writes the raster images and palettes. Raster images and palettes
are written in HDF RIS8 format.

Default:  The filename defaults to ris8.hdf.


Fly File
-fly filename
The -fly parameter is the filename of the fly file PolyView uses
when you enter fly-by mode.

To control an automated flight through a dataset, you provide a
flight plan that contains commands that control the camera
position (from point) and camera focus (at point) of a flight.

To print the current camera position and focus,  press "p" while in
the View window. The string may be copied and incorporated
directly into a fly-by file.

Only two basic fly commands are provided for flights in this
release. Both commands move the initial point to a new position in
a step-by-step fashion.

1.    The command from abs|rel <x> <y> <z> moves the camera
position:

    to (<x>,<y>,<z>) if you use abs

    or

    to (<oldx>+<x>, <oldy>+<y>, <oldz>+<z>) if you specify rel.

2.    The command at abs|rel <x> <y> <z> moves the camera's
focus of attention:

    to (<x>,<y>,<z>) if you use abs

    or

    to (<oldx>+<x>, <oldy>+<y>, <oldz>+<z>) if you specify rel.

Use a semicolon as a comment character. PolyView ignores text
that follows a semicolon on a line.


Fly Demo
For a useful example of how the fly file is used, refer to Appendix B,
"Example Fly File," to view the documentation for the demo.fly
file that runs on the demo.hdf file.


Control Parameters

This section describes the command line parameters that
determine how PolyView initially displays data.

From
-from x y z
The -from parameter specifies the initial camera (x, y, z) position.
Any value in three-space may be used. All three coordinates must
be specified.

Default:  PolyView positions the camera along the z-axis, above the
center point of the data.


Axes
-axes
The -axes parameter tells PolyView to draw coordinate axes.

Default:  The axes are off.


Box
-box
The -box parameter tells PolyView to draw a bounding box.

Default:  The box is off.


Constant
-constant
The -constant parameter tells PolyView to draw constant shaded
polygons.

Default:  Polygons are gouraud-shaded.


Labels
-labels
The -labels parameter toggles whether labels are displayed when
drawing axes or a bounding box.

Default:  PolyView draws the labels.


Lines
-lines
The -lines parameter tells PolyView to draw data as wireframe.

Default:  PolyView draws the polygons.


Points
-points
The -points parameter tells PolyView to draw the a point at each
polygon vertex, instead of polygons.

Default:  PolyView draws the polygons.


Polygons
-polygons
The -polygons parameter tells PolyView to draw data as
polygons.

Default:  PolyView draws the polygons.


At Point
-at_point
The -at_point parameter tells PolyView to draw a six-pointed
jack at the focus of the camera's attention.

Default:  PolyView doesn't display the jack.


View Menu

The View menu (Figure 2.2) contains a number of options that
allow you to adjust the view of the data interactively.


Figure 2.2    View Menu



Projection Submenu
PolyView supports both perspective and orthographic projections.
Figure 2.3 displays the project submenu and its options.

Figure 2.3    Projections
Submenu



By default, the initial viewpoint is a point in the z direction that is
just distant enough so that the entire image is displayed. Figure 2.4
shows a perspective projection.

Figure 2.4    Loaded Demo Image



In an orthographic projection (Figure 2.5) projecting lines are
perpendicular to the plane of projection.

Figure 2.5    Orthographic
Projection of Data



Draw Submenu
Features from the draw submenu (Figure 2.6) draw data as points,
lines, or polygons, depending on the connectivity information
available.

Figure 2.6    Draw Submenu



Points and polygons use colors if scalar information is available;
the lines  options uses color if it is available, and if you have
chosen the gouraud option from the shade menu. If the shade option
is not chosen, you can view the dataset as white. Use the lines
option when you just want to study the intersection of the geometry
in you image. The  polygons option, in the coil image, is the default
view. Choose and view these various options from the draw
submenu.


Shade Submenu
Options in the shade submenu (Figure 2.7) color polygons in two
different styles:  constant or gouraud-shaded. Constant shading
averages the color of the vertices across the polygon as a solid
color. Gouraud shading, on the other hand, uses the IRIS's gouraud
shading hardware when drawing polygons, resulting in
interpolated colors between a polygon's vertices. The data appears
smoother and polygonal boundaries are less apparent. Constant
shading is useful for making the outline of individual polygons
more apparent.

Figure 2.7    Shade Submenu



NOTE:  This version of PolyView offers no support for
individually colored polygons.


Palette Submenu
The palette submenu (Figure 2.8) contains options that allow you to
specify a palette or choose from the standard palettes provided. The
palette function actually maps scalar data to the set of colors, or
palette, that you've specified.

Figure 2.8    Palette Submenu



Choosing a Standard Palette
You can select a standard palette in one of two ways:

1.    Choose a palette from the palette submenu located in the View
window.

    or

2.    Choose a palette from the main menu located in the Palette
window. Notice that the current palette is always reflected in the
Palette window.


Fiddling with the Palette
PolyView contains a palette feature, fiddling, that is found in other
NCSA programs, such as NCSA PalEdit, NCSA Image, and NCSA
ImageIP.

Use the fiddle option in the following way:

1.    Hold down the left or middle mouse button while the cursor is
either in the Palette window.

2.    Move the mouse left and right to compress and expand the
palette, respectively.

3.    Move the mouse up and down to shift the colors in the palette.

All user-defined palettes should map 0 and 255 to the background
and foreground colors (black and white), respectively. These
colors are used for the image background and text.


Overlay Submenu
Features within the overlay submenu (Figure 2.9) display useful
information on top of the data. The overlays help meshes stand out
by showing where their boundaries lie and by providing
orientation information.

Select each of the overlay choices to see the effect they have on your
image. (Refer to Table 2.1 for a review of the overlay options.) Note
that all overlay options toggle off and on.


Figure 2.9    Overlay Submenu



Table 2.1    Overlay Submenu
Options
OPTIONS    PURPOSE

at point    displays the at point as a 3Dplus-sign, or
    jack, in the center of the image.

axes    draws a set of labeled axes.

box    draws a bounding box.

labels    toggles the visibility of the data.

outlines    displays a grid that outlines the actual data
    points in the image.


Animate Submenu
A set of vset groups containing time-varying data may be
animated. All data╤vertex position, connectivity, and scalar
values╤or any subset of datasets may change in any frame of the
sequence.

All animation is cyclic. Backing up past the first frame displays
the last frame. Moving forward past the last frame displays the
first frame.

Once the groups are loaded, the animation may be controlled from
the View menu or the keyboard. The data gathered from each group
is considered as the basis of one frame of the animation.


Using the Animation Submenu
The animate submenu (Figure 2.10) allows either continuous or
single-step animation of a group of frames. Table 2.2 lists the
options in the animate submenu.

Figure 2.10    Animate Submenu



Table 2.2    Animate Submenu
Options
OPTIONS    PURPOSE

reverse    animates the frames backward from the
    current frame.

reverse1    moves the scene back by one frame.

stop    stops any forward or backward animation.

forward1    moves the scene ahead by one frame.

forward    animates the frames forward from the
    current frame (in alphabetical order by
    name of the group).


Using the Keyboard
You may also single-step through an animation using the
keyboard. Press "+" while the cursor is in the View window to
move the animation ahead one frame. Press "-" to move the
animation back one frame.


Fly Option
One of the most important features of NCSA PolyView is the Fly
file, which allows examination of data as it moves through a
specific series of coordinates in space. The "flight" is entirely
described by ASCII files.

To begin the flight:

1.    Select the Fly menu option from the View window.

2.    Select the Fly option again to stop the flight.

For a sample fly-by, refer to Appendix B, "Example Fly File."


Pop Option
Choose the pop option from the View menu to bring a View window
that is "buried" under other windows to the front.


Redraw Option
Choose the redraw option from the View menu to regenerate an
image if it gets corrupted, or if you want to return to its originally
loaded display.


Reset Option
Choose the reset  option to undo the manipulations you've
performed on your image. The image appears on the screen as it
did when initially loaded.


Write HDF Option
Often you will want to study or present to others an image you have
created in PolyView. The option Write HDF writes out the current
frame in the frontmost View window to an HDF 8-bit raster image
file named ris8.hdf. The file will contain the image and its
associated palette, organized in a format suitable for use with and
transfer between other NCSA tools.

You may further manipulate the image by using NCSA Image,
NCSA ImageIP, NCSA X Image, etc. and incorporating it into a
NCSA Layout where you may annotate it. Refer to Appendix D,
"Obtaining NCSA Software" on how to download the documents
via FTP, archive server, or regular mail.


Confirm Submenu
When quitting PolyView, whether by pressing the Esc key in a
graphcis window or bringing up the View window's quit submenu
(Figure 2.11), the Confirm submenu is posted to confirm the
request.

Figure 2.11    Quit Submenu



1.    Choose the Yes, really! option on the submenu to quit.

or

2.    Choose the No, not really. option on the submenu to continue
using PolyView.